Introduction to Web API Architectural Styles

Introduction#

In recent years, APIs' commercial usage has exponentially increased with web and mobile application development. Along with the usage of APIs, it's pretty obvious that APIs can take several different forms. When developers begin to design an API, it’s common to first decide which style/specification to use. More often than not, they opt for REST, as over 90% of developers have adopted this style. However, after analyzing their technical requirements, developers can decide that their API should be handled through a different approach. In this chapter, we’ll discuss architectural styles for APIs and how they differ from each other. Moreover, we’ll examine which architectural style is suitable for which use case.

What is an architectural style?#

An architectural style defines the rules and protocols to be utilized when creating our APIs. They are large-scale, standardized methods through which the system's processes are designed. These predefined structures/templates define a solution for building APIs. Architectural styles are significant because conforming to one is quicker and more efficient than defining our own solution from scratch.

Styles are similar to design patterns because they provide a template on top of which we construct our API. The decision on which architectural style to follow is of great significance because it has long-lasting effects across the entire development timeline. Different constraints, such as API consumers, business preferences, and the purpose of the API, all factor into the final decision. Once settled, it’ll be fairly difficult to change the style later in the development cycle, so we have to be certain when we decide.

Characteristics of an architecture style#

When determining an architectural style, we have to evaluate the characteristics that suit our design problem. Each style practically serves as a template with constraints, so we have to see which suits our API the best. There may be several desirable properties that we want to implement under certain constraints. Let's take a look at some of the properties we may wish to integrate:

Each architectural style implements the elements above to various degrees, so developers choose by placing emphasis on certain objectives. There is no universal answer to what architectural style is the best, so this choice must be carefully deliberated. When choosing a style, developers define some nonnegotiables by picking essential properties that their API should have. Of course, each style may have negative properties, but developers usually highlight favorable principles when evaluating the tradeoffs of the properties we mentioned in the table above. For instance, increasing the performance of our API may have negative impacts on its scalability (probably because we might need to employ more servers in parallel to get the result faster but at the cost of more computation), so these tradeoffs have to be evaluated. In designing there is no free lunch—usually, it's all about trading off one aspect for another.

Various API architecture styles#

We’ll consider three commonly used architectural styles. Keep in mind that each style has its pros and cons, and even if the majority of developers adopt REST, it may not be suited for our API.

REST#

Representational state transfer (REST) is by far the most popular architectural style. The industrial practices for REST API rely heavily on the HTTP protocol and are considered easy to understand, use, and manage. Its familiarity and simplicity are its greatest strengths, but it may struggle in event-driven environments. It performs well when scalability and modifiability are our API's desired characteristics. We'll expand on REST in the upcoming lessons.

RPC#

The remote procedure call (RPC) is the earliest form of API (developed in the 1980s). It mostly deals with databases and widely works on JSON and XML formats. The most vital concept in RPC is the procedure because it doesn't have to function locally and can be handled remotely in the system. The concept has been elaborated on in detail in the Remote Procedure Calls (RPC) lesson.

There are two types of RPCs in regard to architectural style:

• gRPC: In 2015, Google designed a general-purpose RPC, known as gRPC. It's a framework that implements RPC-based APIs using protocol buffers for serialization. It’s constantly being upgraded with new features and has reduced latency due to its compression methods.

• SOAP: Simple object access protocol (SOAP) was developed in 1999 by Microsoft. It uses XML, and to implement it, we have to stick to strict rules about encoding, structuring messages, and handling requests. It has built-in error handling, and each error will be accompanied by the relevant information to resolve it. Due to the strict and inflexible nature of SOAP, the requests can get large, which can carry overheads. Few major real-world services still use SOAP, and it’s largely considered an obsolete technology today.

GraphQL#

GraphQL serves as the query language specification for APIs. It's a newer technology developed by Facebook in 2012. It was developed to overcome the shortcomings of REST, providing an alternative to developers. Applications like GitHub and Yelp have opted to use GraphQL over REST, even though its release was fairly recent.

Chapter overview#

Our goal in this chapter is to expand on these architectural styles that enable us to design APIs. We'll discuss three design choices, each with its advantages and drawbacks. Different APIs will require different styles because there isn't a singular answer for all design needs. Technically, the developers of the API will have to examine and decide which style conforms to their idea the most, taking each of their strengths and weaknesses into consideration.

We’ll divide our focus into three architectural styles: REST, GraphQL, and gRPC. Each style will be expanded on, and we'll compare the pros and cons of each style toward the end. After emphasizing each style, we'll be adept at making our final decision about the architectural style of our API.